//! # 性能管理核心接口定义
//! 
//! 定义性能优化相关的核心trait接口，采用面向接口编程设计。
//! 包含连接池管理、内存管理、异步任务池等核心抽象。

use rustcloud_core::{ServiceResult, ServiceError};
use std::sync::Arc;
use std::collections::HashMap;
use std::time::{Duration, Instant};
use async_trait::async_trait;

/// 连接池管理接口
/// 
/// 定义了连接池的核心操作，支持通用的连接类型和灵活的配置管理。
/// 采用泛型设计，支持多种连接类型（数据库、HTTP、TCP等）。
#[async_trait]
pub trait ConnectionPool<T>: Send + Sync
where
    T: Send + Sync + 'static,
{
    /// 获取连接
    /// 
    /// 从连接池中获取一个可用的连接。如果池中没有可用连接，
    /// 将创建新连接或等待现有连接释放。
    /// 
    /// # 返回值
    /// 
    /// - `Ok(PooledConnection<T>)` - 成功获取连接
    /// - `Err(ServiceError)` - 获取失败，可能是超时或连接创建失败
    /// 
    /// # 超时处理
    /// 
    /// 该方法将按照配置中的超时时间等待连接可用。
    async fn acquire(&self) -> ServiceResult<PooledConnection<T>>;

    /// 释放连接
    /// 
    /// 将连接返回到连接池中供后续使用。该方法会检查连接的健康状态，
    /// 如果连接已损坏则不会返回池中。
    /// 
    /// # 参数
    /// 
    /// * `connection_id` - 要释放的连接ID
    /// 
    /// # 返回值
    /// 
    /// - `Ok(())` - 成功释放连接
    /// - `Err(ServiceError)` - 释放过程中发生错误
    async fn release(&self, connection_id: &str) -> ServiceResult<()>;

    /// 验证连接是否可用
    /// 
    /// 检查指定连接的健康状态，确保其可以正常使用。
    /// 
    /// # 参数
    /// 
    /// * `connection_id` - 要验证的连接ID
    /// 
    /// # 返回值
    /// 
    /// - `Ok(true)` - 连接有效且可用
    /// - `Ok(false)` - 连接无效或不可用
    /// - `Err(ServiceError)` - 验证过程中发生错误
    async fn validate_connection(&self, connection_id: &str) -> ServiceResult<bool>;

    /// 获取连接池统计信息
    /// 
    /// 返回连接池的实时统计数据，包括连接数量、使用情况等。
    /// 
    /// # 返回值
    /// 
    /// 连接池统计信息结构体
    async fn get_stats(&self) -> PoolStats;

    /// 初始化连接池
    /// 
    /// 预创建最小数量的连接，确保连接池处于就绪状态。
    async fn initialize(&self) -> ServiceResult<()>;

    /// 关闭连接池
    /// 
    /// 优雅关闭所有连接，清理资源。
    async fn shutdown(&self) -> ServiceResult<()>;

    /// 清理过期连接
    /// 
    /// 清理长时间未使用的空闲连接，释放资源。
    /// 
    /// # 返回值
    /// 
    /// 被清理的连接数量
    async fn cleanup_expired(&self) -> ServiceResult<usize>;
}

/// 连接工厂接口
/// 
/// 定义了创建、验证和销毁连接的标准操作。
#[async_trait]
pub trait ConnectionFactory<T>: Send + Sync {
    /// 创建新连接
    /// 
    /// 根据配置创建一个新的连接实例。
    /// 
    /// # 返回值
    /// 
    /// - `Ok(T)` - 成功创建的连接
    /// - `Err(ServiceError)` - 创建失败
    async fn create_connection(&self) -> ServiceResult<T>;
    
    /// 验证连接是否有效
    /// 
    /// 检查连接的健康状态和可用性。
    /// 
    /// # 参数
    /// 
    /// * `connection` - 要验证的连接引用
    /// 
    /// # 返回值
    /// 
    /// 连接是否有效
    async fn validate_connection(&self, connection: &T) -> bool;
    
    /// 销毁连接
    /// 
    /// 安全释放连接资源。
    /// 
    /// # 参数
    /// 
    /// * `connection` - 要销毁的连接实例
    /// 
    /// # 返回值
    /// 
    /// - `Ok(())` - 成功销毁连接
    /// - `Err(ServiceError)` - 销毁过程中发生错误
    async fn destroy_connection(&self, connection: T) -> ServiceResult<()>;

    /// 获取连接类型名称
    /// 
    /// 返回连接类型的描述性名称，用于日志和监控。
    fn connection_type(&self) -> &str {
        std::any::type_name::<T>()
    }

    /// 检查是否支持连接验证
    /// 
    /// 指示工厂是否支持连接有效性验证。
    fn supports_validation(&self) -> bool {
        true
    }
}

/// 内存管理器接口
/// 
/// 定义了内存分配、释放和垃圾回收的核心操作。
#[async_trait]
pub trait MemoryManager: Send + Sync {
    /// 创建内存池
    /// 
    /// 创建一个指定配置的内存池用于高效分配。
    /// 
    /// # 参数
    /// 
    /// * `name` - 内存池名称
    /// * `block_size` - 块大小（字节）
    /// * `max_blocks` - 最大块数量
    async fn create_pool(&self, name: String, block_size: usize, max_blocks: usize) -> ServiceResult<()>;

    /// 分配内存
    /// 
    /// 从指定内存池中分配一块内存。
    /// 
    /// # 参数
    /// 
    /// * `pool_name` - 内存池名称
    /// 
    /// # 返回值
    /// 
    /// 分配的内存块
    async fn allocate(&self, pool_name: &str) -> ServiceResult<Vec<u8>>;

    /// 释放内存
    /// 
    /// 将内存块返回到对应的内存池中。
    /// 
    /// # 参数
    /// 
    /// * `pool_name` - 内存池名称
    /// * `block` - 要释放的内存块
    async fn deallocate(&self, pool_name: &str, block: Vec<u8>) -> ServiceResult<()>;

    /// 执行垃圾回收
    /// 
    /// 清理未使用的内存，释放系统资源。
    /// 
    /// # 返回值
    /// 
    /// 释放的内存大小（字节）
    async fn garbage_collect(&self) -> ServiceResult<usize>;

    /// 获取内存统计信息
    /// 
    /// 返回内存使用的详细统计数据。
    async fn get_stats(&self) -> MemoryStats;

    /// 启动自动垃圾回收
    /// 
    /// 根据配置启动后台垃圾回收任务。
    async fn start_auto_gc(&self);
}

/// 异步任务池接口
/// 
/// 定义了异步任务调度和管理的核心操作。
#[async_trait]
pub trait AsyncTaskPool: Send + Sync {
    /// 提交任务
    /// 
    /// 将任务提交到任务池中异步执行。
    /// 
    /// # 参数
    /// 
    /// * `task` - 要执行的任务函数
    /// 
    /// # 返回值
    /// 
    /// - `Ok(())` - 任务成功提交
    /// - `Err(ServiceError)` - 提交失败（如队列满）
    async fn submit<F>(&self, task: F) -> ServiceResult<()>
    where
        F: FnOnce() + Send + 'static;

    /// 提交带返回值的任务
    /// 
    /// 提交异步任务并返回Future用于获取结果。
    /// 
    /// # 参数
    /// 
    /// * `task` - 要执行的异步任务
    /// 
    /// # 返回值
    /// 
    /// 任务执行的Future
    async fn submit_async<F, T>(&self, task: F) -> ServiceResult<tokio::task::JoinHandle<T>>
    where
        F: std::future::Future<Output = T> + Send + 'static,
        T: Send + 'static;

    /// 获取任务统计信息
    /// 
    /// 返回任务池的运行状态和统计数据。
    async fn get_stats(&self) -> TaskStats;

    /// 关闭任务池
    /// 
    /// 停止接受新任务，等待现有任务完成。
    async fn shutdown(&self) -> ServiceResult<()>;

    /// 强制关闭任务池
    /// 
    /// 立即停止所有任务和工作线程。
    async fn force_shutdown(&self) -> ServiceResult<()>;
}

/// 连接状态枚举
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ConnectionState {
    /// 空闲状态
    Idle,
    /// 活跃使用中
    Active,
    /// 验证中
    Validating,
    /// 错误状态
    Error,
}

/// 池化连接结构
#[derive(Debug)]
pub struct PooledConnection<T> {
    /// 连接对象
    pub connection: T,
    /// 连接ID
    pub id: String,
    /// 创建时间
    pub created_at: Instant,
    /// 最后使用时间
    pub last_used: Instant,
    /// 使用次数
    pub use_count: u64,
    /// 连接状态
    pub state: ConnectionState,
}

impl<T> PooledConnection<T> {
    /// 创建新的池化连接
    pub fn new(connection: T) -> Self {
        let now = Instant::now();
        Self {
            connection,
            id: format!("conn_{}", std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()),
            created_at: now,
            last_used: now,
            use_count: 0,
            state: ConnectionState::Idle,
        }
    }

    /// 标记连接为使用中
    pub fn mark_used(&mut self) {
        self.last_used = Instant::now();
        self.use_count += 1;
        self.state = ConnectionState::Active;
    }

    /// 标记连接为空闲
    pub fn mark_idle(&mut self) {
        self.state = ConnectionState::Idle;
    }

    /// 检查连接是否过期
    pub fn is_expired(&self, idle_timeout: Duration) -> bool {
        self.last_used.elapsed() > idle_timeout
    }
}

/// 连接池统计信息
#[derive(Debug, Default, Clone)]
pub struct PoolStats {
    /// 总连接数
    pub total_connections: u32,
    /// 活跃连接数
    pub active_connections: u32,
    /// 空闲连接数
    pub idle_connections: u32,
    /// 获取连接次数
    pub acquire_count: u64,
    /// 释放连接次数
    pub release_count: u64,
    /// 创建连接次数
    pub create_count: u64,
    /// 销毁连接次数
    pub destroy_count: u64,
    /// 验证失败次数
    pub validation_failures: u64,
}

/// 内存统计信息
#[derive(Debug, Default, Clone)]
pub struct MemoryStats {
    /// 总分配内存（字节）
    pub total_allocated: usize,
    /// 当前使用内存（字节）
    pub current_used: usize,
    /// 分配次数
    pub allocation_count: u64,
    /// 释放次数
    pub deallocation_count: u64,
    /// GC执行次数
    pub gc_count: u64,
    /// 内存池数量
    pub pool_count: usize,
}

/// 任务统计信息
#[derive(Debug, Default, Clone)]
pub struct TaskStats {
    /// 提交的任务数
    pub submitted_tasks: u64,
    /// 完成的任务数
    pub completed_tasks: u64,
    /// 失败的任务数
    pub failed_tasks: u64,
    /// 当前队列长度
    pub queue_length: usize,
    /// 工作线程数
    pub worker_count: usize,
}